Skip to content

Add accessibility checklist for native mobile experiences#41

Open
janmaarten-a11y wants to merge 17 commits intomainfrom
mobile-a11y-checklist
Open

Add accessibility checklist for native mobile experiences#41
janmaarten-a11y wants to merge 17 commits intomainfrom
mobile-a11y-checklist

Conversation

@janmaarten-a11y
Copy link
Copy Markdown
Collaborator

@janmaarten-a11y janmaarten-a11y commented Apr 30, 2026

Closes #36

Overview

This pull request adds a comprehensive accessibility checklist specifically for native mobile applications (iOS and Android) in the new file checklists/mobile-checklist.md. The checklist consolidates WCAG 2.2 requirements, W3C mobile guidance, and platform best practices into actionable items for designers and engineers working on native mobile experiences. It covers all major accessibility considerations, provides annotation guidance, and includes resources and testing recommendations.

This document provides a comprehensive checklist for accessibility considerations specific to native mobile experiences, including guidelines, best practices, and resources for iOS and Android applications.
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Co-authored-by: Eric Bailey <ericwbailey@users.noreply.github.com>
@janmaarten-a11y janmaarten-a11y marked this pull request as ready for review April 30, 2026 21:25
@janmaarten-a11y janmaarten-a11y requested a review from a team as a code owner April 30, 2026 21:25
Copilot AI review requested due to automatic review settings April 30, 2026 21:25
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new, mobile-specific accessibility checklist to complement the existing designer and engineering checklists, addressing mobile-native patterns and audit considerations requested in issue #36.

Changes:

  • Introduces checklists/mobile-checklist.md with an iOS/Android-focused accessibility checklist (WCAG 2.2 + WCAG2Mobile/WCAG2ICT guidance + platform best practices).
  • Includes annotation pointers, testing recommendations, and a curated set of resources for mobile accessibility work.
Show a summary per file
File Description
checklists/mobile-checklist.md Adds a comprehensive native mobile accessibility checklist covering key areas (color, hierarchy, gestures, platform behavior, navigation, etc.).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  • Files reviewed: 1/1 changed files
  • Comments generated: 3

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Copy link
Copy Markdown
Contributor

@joelamyman joelamyman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@janmaarten-a11y as always, this is such a fantastic resource - super comprehensive and easy to follow!

I've left some minor comments, please feel free to use/dismiss them as you see necessary! If there are any questions, please let me know 😄

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
- [ ] **Roles and traits are specified per platform**
- iOS uses traits (button, header, adjustable, selected). Android uses roles and state descriptions. Annotate both if you ship to both.
- [ ] **Hints are used only for non-obvious interactions**
- Don't put critical info in hints. Users can disable them, and they're announced last.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an excellent point to raise as its something that feels like its missed quite often, so great to include it here!!

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
- [ ] **Stock components use the platform's native accessibility behavior**
- When using a system component, toggle "Follow stock native pattern" in your Mobile Details annotation and link to the platform docs.
- [ ] **Platform conventions are respected**
- Back navigation, modal dismissal, and primary action placement differ between iOS and Android. Don't force one platform's pattern onto the other.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a really important point for usability, so it's great to see it included here! 🙌

Updated language for clarity and added guidance on accessibility practices in mobile app design.
Added a checklist for mobile accessibility considerations.
Updated checklist items to include links for Smart Invert, color correction, VoiceOver, TalkBack, Reduce Motion, iOS Dynamic Type, and Android Font Size Scaling for better accessibility guidance. h/t @ericwbailey
@janmaarten-a11y
Copy link
Copy Markdown
Collaborator Author

Thanks all for the thorough and thoughtful review! 🙌 I've pushed the remaining updates addressing every open comment.

What changed in this round:

  • Single-bullet list cleanup — finished the audit Eric flagged on §2 Exercises. Converted the single-item "Annotations that can help" lists in §5, §7, §8, and §13 to inline sentences so screen reader users aren't told there's more list content when there isn't.
  • Intro restructure — split the per-interaction guidance and audit notes into two paragraphs, each with a short "why" explaining when you'd reach for that resource.
  • Decorative explainer — added a link to the W3C alt-text decision tree in §3 since deciding what's actually decorative is the hard part.
  • Reading order on framework-determined platforms — new item in §2 about favoring simple, predictable layouts since some frameworks (notably React Native) don't expose an API to override OS-determined reading order. Thanks @joelamyman for the prompt.
  • Label item expansion — broke §3's Label caption into three sub-bullets covering purpose, Voice Control / Voice Access programmatic association, and icon-only labels.
  • Buttons and links wording — adopted Joel's clearer phrasing about considering the action when applying a role.
  • Orientation completeness — added "all functionality and content must remain available across orientations" to §7.
  • Voice Control caption — unpacked the "drift apart" phrasing to call out both visual and programmatic relationships.
  • Errors expansion — §8's error item now covers text-based identification, fix suggestions where determinable, and screen reader announcement.
  • Reachable AND operable — §10 now makes it explicit that external keyboard support means the interaction must work, not just be focusable.
  • iOS/Android jargon links on first mention — per @ericwbailey's question. Linked VoiceOver, TalkBack, Voice Control, Voice Access, Reduce Motion, Switch Control, Switch Access, Smart Invert, color correction, Dynamic Type, and Android's Font Size Scaling on first mention. We can carry this pattern over to the designer and engineering checklists in a follow-up.

I also added links to this new doc from the repo README.md and the Mobile annotations tutorial.

What I didn't take:

  • @joelamyman's GOV.UK number input post — it's a great read but the nuance felt too deep for the format. Worth revisiting if we ever do a deeper forms guide.

Re-requesting review from @ericwbailey and @joelamyman. Thanks again for making this much sharper than where it started!

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Copy link
Copy Markdown
Contributor

@joelamyman joelamyman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just completed another review, all of the changes look good to me - I caught a TPGi link that should be changed to Vispero after their recent rebranding, but that's it! 😄

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
@janmaarten-a11y
Copy link
Copy Markdown
Collaborator Author

Thanks for the deep dive @julianmka, and for the second pass @joelamyman! 🙌 This round added a lot of mobile-specific sharpness that the earlier drafts were missing.

What changed in this round:

  • Color (§1) — Added Android Accessibility Scanner to suggested tools with a note that it detects contrast issues. Updated the TPGi → Vispero rebrand on the Colour Contrast Analyzer link. I hadn't even realized they rebranded.
  • Hierarchy (§2) — New item recommending a prominent heading near the top of content when a screen has no title bar.
  • Content (§3) — Added an iOS sub-bullet on .accessibilityInputLabels for Voice Control alternate names (great for icon buttons with long primary labels). Updated the iOS API for hiding decorative elements from accessibilityElementsHidden to .accessibilityHidden(true). Added an Appt reference for SC 3.1.2 Language of Parts since it's varsity-level on native.
  • Interactivity (§5) — Reworked the buttons vs links guidance to reflect mobile convention rather than web. On mobile, buttons handle in-app navigation and system functions; links are reserved for content opening in the device browser or a web view. Swapped the Apple HIG resource link for the platform-level Accessibility (Mobility) page.
  • Gestures (§6) — New item on supporting the VoiceOver scrub gesture for custom components on iOS. Reframed the "primary actions" item since single tap is the foundational gesture, not something to reserve. Replaced "single-point" with "single-tap" since the WCAG term reads as jargon outside an audit context.
  • Touch and keyboard (§10) — Repositioned the focus order item as an exception for complex layouts, since being prescriptive about focus order on simple screens can be a real footgun. Added "For example" before the slider example for clarity.
  • Platform functions (§12) — Removed the Safari example since iOS users can change their default browser. Updated language from "live regions" to "live accessibility announcements" throughout, since live regions are a web concept and the native equivalent has different terminology and APIs. Kept the Figma component name "Mobile Live Region Announcement" intact and added a clarifying note about it.
  • Notifications (§13) — Same terminology update from live regions to live accessibility announcements.

Re-requesting review from @julianmka and @joelamyman.

@janmaarten-a11y janmaarten-a11y requested a review from joelamyman May 6, 2026 20:30
Added exercises for evaluating design element necessity and clarified error handling in forms.
@janmaarten-a11y janmaarten-a11y requested a review from julianmka May 6, 2026 21:44
Copy link
Copy Markdown

@julianmka julianmka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. Had a few more tweaks because I'm difficult that way. So appreciate the care going into this!

Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md Outdated
Comment thread checklists/mobile-checklist.md
Comment thread checklists/mobile-checklist.md Outdated
@janmaarten-a11y
Copy link
Copy Markdown
Collaborator Author

@julianmka Love the suggestions. They should all be applied. This commit diff shows most of the changes, though I added the "scaled up" text fix in a second commit.

@janmaarten-a11y janmaarten-a11y requested a review from julianmka May 6, 2026 23:00
Copy link
Copy Markdown

@julianmka julianmka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! Only one comment this time 😅

Comment thread checklists/mobile-checklist.md Outdated
Copy link
Copy Markdown

@julianmka julianmka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commented on @joelamyman's number input link

Clarified the explanation of screen titles and their application in mobile accessibility.
Updated checklist items for clarity and consistency in wording, including links and emphasis on accessibility standards.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature request] Add a Mobile variant to the Checkpoints component

5 participants